Software Vault: The Diamond Collection

home *** CD-ROM | disk | FTP | other *** search

/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr47 / sch250.zip / GENERAL.DOC < prev next >

Wrap

Text File | 1995-02-16 | 28KB | 639 lines

SCHOONER Version 2.50 GUI User's Manual DISCLAIMER AND WARRANTY the small print Users of SCHOONER must accept this disclaimer of warranty: The program is provided "AS IS" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you (and not Jonathan Cook) assume the entire cost of all necessary servicing, repair or correction. Jonathan Cook does not warrant that the function contained in the program will meet your requirements or that the operation of the program will be uninterrupted or error free. In no event will Jonathan Cook be liable to you for any damages including any lost profits, lost savings or other incidental or consequential damages arising out of the use or inability to use such program or for any claim by any other party. Please read the Schooner license agreement found in the file LICENSE.DOC. By using this software, you are bound by the terms of the license agreement. DEFINITION OF SHAREWARE Applies to shareware version only Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. SCHOONER 2.50 is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using SCHOONER and continue to use SCHOONER after a reasonable trial period, you must make a registration payment of $39.95 to Jonathan Cook. The $39.95 registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. Commercial users of SCHOONER must register and pay for their copies of SCHOONER within 30 days of first use or their license is withdrawn. Site-License arrangements may be made by contacting Jonathan Cook. Anyone distributing SCHOONER for any kind of remuneration must first contact Jonathan Cook at the address below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering SCHOONER immediately (However Jonathan Cook must still be advised so that the distributor can be kept up-to-date with the latest version of SCHOONER.). You are encouraged to pass a copy of SCHOONER along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of the SCHOONER system. Note: Clipper(r), Dbase and Foxbase are registered names and/or trademarks of Computer Associates, Borland and Microsoft. Any other name references, expressed or implied, are registered names and/or trademarks of their respective developers/manufacturers. INTRODUCTION Schooner is a powerful, full featured database programming language similar to other Xbase languages. The Schooner development environment revolves around the powerful text editor. From this command center you can develop and control your application. You can write source code, code reports, create and modify database structures, manipulate data and execute your code... All from within the text editor. In addition, when errors are detected, they are displayed in a red box. Schooner then places the cursor on the line where the error was detected, even if the error occurred in a module other than the one you were editing. Command and function help are just a keypress away. All language documentation is on-line and available with the F1 help key. Getting Started. Schooner is very easy to use. Simply copy the Sch250.exe file to a subdirectory and change to that subdirectory. (Note: If you have downloaded Schooner from an on-line service, substitute the file Sch250.zip and use the PKZIP utility to decompress the file). Decompress the Schooner files for the registered version by typing: sch250.exe (for the shareware version, please use the latest version of PKZIP.) All of the files will decompress and you are ready to go. To begin Schooner type: Schooner and press ENTER. The Schooner logo will appear (Note: The Schooner shareware logo will appear with the shareware version). Press any key and the editor will appear. While the editor appears simple, it will reveal a great deal with the F1 key. Press F1 and the help screen for the editor will appear. This screen details all of the commands available to the editor. You can cut and paste blocks of text, read and write files (and blocks) to and from disk and create and edit data files. Press the F2 key from the editor help screen and a list of all of the commands and functions available to the language appear. Scroll through the list. A short description accompanies each command or function. Press ENTER on a highlighted line and the complete description for that command or function appears. Each description contains the command or function name, the syntax, the use, a parameter description, return values, a general description and an sample piece of code. Press ESC and you will back out of the help system the same way you went in. Viewing an Example An entire demo application is available for your viewing pleasure. Press F8 and enter the file name: DEMO250.PRG and press ENTER. The program DEMO250 will appear on the screen. To experienced XBASE programmers the code will immediately look familiar. Use the arrow keys to scroll up and down. When you are done viewing the code, execute it. Press Alt-R Schooner assumes you want to run the code that is loaded into the editor. You will note that the file name has changed to DEMO250.RUN. In the blink of an eye the code has been saved and converted into the RUN format for execution. In fact all programs (.prg) are automatically saved and converted to .run format whenever you press Alt-R (or CTRL-W). This assures that your .prg and .run are in synch at all times. Play with the demo. When done click on the EXIT icon from the start- up screen and you will return to the exact location in the editor at which you left when you pressed Alt-R. The various programs that make up the demo are an excellent example of Schooner code. As mentioned above, if you have experience in Dbase(r), Foxbase(r) or Clipper(r) you will recognize Schooner right away. Writing Your First Program From a blank editor screen press F8 and enter a new program name. Call it 'TEST.prg' for this example and press ENTER. Type in the following lines of code. Press ENTER after each line. clearscrn() superbox(00,00,24,79,.T.,"",.f.) mvcount=0 do while mvcount<50 message('The counter is: '+alltrim(str(mvcount)),'OFF') mvcount=mvcount+1 enddo message('DONE!!!') quit When you are done press ALT-R. This will save and convert your code to .RUN format. Press ENTER to accept the program to run and watch it go... This little program simply displays a counter on the screen. But it does give you a good idea of how simple a Schooner program is to write and run. In order to understand the code better, press F1 then F2 and look up each command and function in the on-line help. Starting the Schooner Development System in Run Mode This version of Schooner now comes with the option to run an application directly from the command line. To run your program directly from the DOS command line follow this format: Schooner <Filename>.run /r Example: schooner myprog.run /r The .RUN extension is required. The /R parameter tells Schooner to run your program directly and bypass the editor. The Schooner logo will appear. Press any key and your application will begin. The /R option is available for the convenience of developers who might wish to run their personal applications or who wish to use their own editors to write code. The /R option should not be used to release runtime versions of your applications. To do so will use more memory then the runtime system as well as display the Schooner logo each time your application is run. Compiling Your Application .prg Program Files The compile process is normally automatic when you press ALT-R within the Schooner editor. This conveniently keeps your source .prg code and your compiled .run code in synch. However, you may wish to write your code in another editor of your choice (be sure to save your code in straight ASCII code without any hidden formatting characters). If so, you will need to compile your .prg code into .run format. This is easily done with the stand alone Schooner COMPILE program (not included with the shareware version of Schooner. It is only available with your Schooner registration). The compile program gives you the added benefit of optimizing your .run code a bit by allowing your to remove blank lines and comments from your .run module. The compile program is run from the DOS prompt with the format: compile <filename>.prg </NB> </NC> Where <filename> is the name of your .prg program. The .prg extension is required. The two optional parameters are /NB to remove blank lines and /NC to remove comments (note that removing blank lines and comments during the compile process only removes the lines from the .run module and not your .prg source code). Since using your own editor in conjunction with the compile program does not automatically synch your .run module with your .prg source code, it is your responsibility to be sure that your .run modules are compiled and in synch with your source code when a change in your source code occurs. To run your newly compiled .run files, simply run them like any other .run module with the Schooner runtime module (not included with the shareware version of Schooner. It is only available with your Schooner registration). Or you can run them with the Schooner development program by passing the /R parameter to bypass the editor (see above). Although Schooner does not contain a MAKE facility, it is very easy to create a simple make facility using the compile program within a controling batch file. For example, you can create a batch file to reduce your typing effort: cls compile %1 /NB /NC This simple batch file will compile the .prg file passed to it and remove blank lines and comments. You can expand this batch file to rebuild an entire application by coding multiple compile calls: compile myprog1.prg /NB /NC compile myprog2.prg /NB /NC compile myprog3.prg /NB /NC compile myprog4.prg /NB /NC . . . etc. As you can see, compiling your applications with the compile program is quick, easy and provides the added flexibility of using the editor of your choice. Using the Report Writer The Schooner stand alone report writer (not included with the shareware version of Schooner. It is only available with your Schooner registration) allows you to create .frm and .lbl report and label format files for use with the REPORTFORM() function in Schooner. Because the report writer allows you to create report templates instead of writing custom report code, you can save significant time when creating basic reports. To run the report writer, at the DOS prompt type: Reporter This will start the report writer. All documentation is on-line and available by pressing the F1 key. Schooner Technical Specifications In a nutshell, Schooner has virtually all of the capabilities of Dbase III plus(r) and Clipper(r) Summer '87. In addition, Schooner supports a whole set of graphics, imaging and mouse functions not found in either of the above languages. System Specifications: IBM compatible computers with 640k bytes of RAM, hard drive, one floppy, DOS 5.0 (developed in 5.0 but should work in version 3.30 or higher) and an EGA or VGA color monitor for Graphical User Interface (GUI) development. Field types: Character........32K Numeric..........Max 19 bytes Date.............8 bytes Logical..........1 byte Memo.............Max 64k Indexing: Schooner supports indexing with the .NTX extension. Arrays: Single dimensional arrays. Any data type. Arrays are declared with the PUBLIC command. Files: Database........... .dbf Memos.............. .dbt Labels............. .lbl Reports............ .frm Program modules.... .prg Run modules........ .run Graphics Images.... .PCX Note: IMGSAVE() and IMGRESTORE() graphics images do not require extensions. Procedures and Functions: Schooner handles procedures much the same way as Dbase III plus(r). Schooner User Defined Functions are handled as described in the on-line documentation. Functions can be included in lines of code like any compiled function but they cannot pass parameters (this is done by declared public variables), contain nested Schooner defined functions or call other Schooner procedures. Work Areas: Schooner supports 9 open files (work areas) and index combinations but not to exceed the number of files declared to DOS. Each data file must reside in its own work area and can be accessed by alias name or the FSELECT() function. Public: All variables in Schooner are declared as public (available to all procedures and functions) either automatically when assigned (mvname='John') or with the PUBLIC command. All variable names start with the letters MV and can contain a maximum of 10 letters. Operations: Math: + addition - subtraction * multiplication / division % modulus ^ raised powers ** " " Order: Operations are solved from left to right. Parentheses are solved first Exponentiation are solved second Multiplication and division are third Addition and subtraction are last Relational: < less than > greater than = equal <> not equal <= less than or equal >= greater than or equal $ contained within == exactly equal Logicals: .and. .or. .not. Strings: + join two strings together - joins two strings together but trims any trailing spaces from the first. Passing DOS Variables to Schooner Applications: You can pass DOS information to Schooner by declaring a DOS variable with the SET command. Use the GETE() function within Schooner to get the environment variable from DOS. Be sure that the DOS variable you reference in the GETE() function is upper case. See GETE(). Memory Management You can manage the use of memory with the following standard CLIPPER DOS environment variable settings: Set CLIPPER=Vxxx;Rxxx;Fxxx;Sx;Exxx 'V' controls memory (in kbytes) used for tracking memory variables. If not defined then 20% of available memory is used (up to 44k) for variables. Since only 22 bytes are used for each variable, you can provide more memory to the rest of the system by declaring only that which is really needed for variables to Schooner. 'R' controls the RAM used for index buffers (these are internal buffers and not those declared in your config.sys) and the SHELL() function. Unless you are going to SHELL() to DOS, set this to the minimum 16K. 'F' overrides the files setting in Config.sys (but cannot exceed it). This can be helpful in managing the number of open files Schooner can use. 'S' can help to control snow effects on older monitors. Set to 1 (one) will help eliminate snow. 'E' controls the amount of Expanded memory Schooner can use, up to a maximum of 1 megabyte. When available, expanded memory is only used for index buffering. Out of memory conditions created as a result of the MS DOS 5.00 and 6.00 EMM386.sys NOEMS option can be eliminated by setting E to 000. You do not need to declare the CLIPPER variable to DOS, Schooner will simply use the defaults. However, in tight memory environments it can help your applications manage memory better. Programming GUI Applications One of the great advantages to creating Graphical User Interface (GUI) applications in Schooner is that it is as easy as creating text applications. In fact, you will develop GUI applications in exactly the same way as text applications. The only difference is that you will substitute GUI screen display functions for text screen display functions. All other non-screen display functions work the same. In addition, you can switch back and forth between GUI screens and text screens as desired, saving and restoring both types of screens as needed. The most difficult part of GUI programming is dealing with color palette oddities. Color palettes are the internal tables that track what colors appear on the screen. Schooner supports EGA 640x350 16 color mode and VGA 640x480 16 color mode for all GUI functions. Schooner also supports VGA 320x200 256 color mode for most GUI functions. The difficult aspect of color palettes is due to the fact that there is no color palette standard for IBM systems. Each image created for display on an IBM system contains its own color palette. This palette can be completely different from another image, even though the images where designed to be displayed in the same mode and resolution. The end effect is that the last image to be displayed instantly applies its palette to the system and quite often destroys the previous images and elements on the screen. There are two solutions to this dilemma: The first is to never use two images on the same screen at the same time and to never use an image on the screen at the same time that other GUI elements are on the screen. This solution, for obvious reasons is worthless. The second solution is to be sure that all elements on the screen at the same time have the same palette. This solution creates its own difficulties but is much more practical. The easiest way to get images with the same palettes is to get them all from the same source where you can control the palette. Most paint programs will apply the same palette to each picture created in it. This works well for creating icons (for Schooner, these are simply small .PCX images) as well as wallpapers and static screens designed for background purposes. Scanned images which use the same scanner and software will generally also fall into this category. However, the scanning software, if different from the paint program, may have a different palette. One possible way around this is to establish a standard palette and default background in your paint program and then import your scanned image on top of the background. This may set the palette for your image. Experiment with this idea as each paint program is different. Another way to standardize your palettes is with specialty imaging software that has tools specifically designed to equalize palettes. This is the best solution but may cost more. When building a GUI screen follow these general guidelines: Set your GRAPHMODE() with 0,2 or 6 Establish a background wallpaper. Wallpaper is nothing fancy, it is simply a full screen .PCX image that is "FLASHed" onto the screen (see the IMGPCX() function). Wallpaper can be any design you like. Be sure its format matches the GRAPHMODE() set and has the palette desired. From this point on, you are free to draw your GUI elements as well as "SCROLL" as many .PCX images onto the screen as you like (provided they have the same palette as your wallpaper). When setting the GRAPHCOLOR() and color parameters for each of your GUI elements be sure that you know the first 16 colors of the palette that has been set. These are the colors that will make up your GUI elements. The easiest way to view the first 16 colors is to write a little program which loops through the first 16 colors and displays a box with each color change. For all practical purposes, developing GUI applications in 320x200 256 color mode is not advisable. There is just not enough screen resolution to display the objects necessary to create a useful application. This mode is good however, for displaying full screen images and you can take advantage of it for just that. Programming the Mouse The mouse is automatically available in graphics mode as soon as the MSRESET() function is called. It becomes visible and active when MSCRSORON() is called and becomes invisible when MSCRSOROFF() is called. There is really nothing special about programming for the mouse. For the most part you will call the MSWAIT() function to pause your program and wait for a mouse event. When a mouse event occurs, your program will continue. Much like checking for a menu selection, you will use a series of IF-ENDIF statements to check the MSINSIDE() function. MSINSIDE() returns a .t. if the last mouse event occurred within a specified area. The only mouse oddity to be aware of is this: If the mouse is left turned on and active at the time that a GUI screen element is being created, the mouse can leave "droppings" and "trails" behind. This looks like holes in the screen when the mouse is next moved. Simply turn the mouse off when new GUI elements are to be drawn and turn it back on when complete. See the DEMO250 version 2.50 demonstration program for examples. Network Applications Schooner should be compatible with most local area networks that recognize the Clipper(r) method of record and file locking. However, we do not have a LAN of our own to test with and cannot guarantee networking compatibility. In general, writing applications for networks is pretty easy. Observe the following: Open 'shared', all files that reside on servers that will be shared. Open other files (especially those that reside on the node PC) as exclusive. All shared files must use record or file locking in order to lock the record or file for exclusive use by the requesting node. Only the locking node can modify the record or file. Others, however, can read the file. Be sure to unlock the record or file when done so others can access the record or file. Reference the NETERR() function when performing network activities. This can help you determine error conditions that might arise. It is recommended that you use record locking for virtually all network activities. This leaves the rest of the file open for other users to access and provides better speed as more users access the file. However, OPEN() the file exclusively for such activities as FZAP() which will delete and pack the whole file. Error Messages Please see the file ERRORS.DOC for a description of Schooner runtime error messages.